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Abstract 

Automated text generation requires a 
underlying knowledge base from which 
to generate, which is often difficult to 
produce. Software documentation is one 
domain in which parts of this knowledge 
base may be derived automatically. In 
this paper, we describe drafter, an au- 
thoring support tool for generating user- 
centred software documentation, and in 
particular, we describe how parts of its 
required knowledge base can be obtained 
automatically. 



1 Introduction 

Automated text generation is becoming an attrac- 
tive technology because it allows for the genera- 
tion of text in different styles and in different lan- 
guages from a single underlying knowledge base. 
The well-known problem with the technology is 
that this knowledge base is often difficult to build. 
In most research generation systems, this knowl- 
edge base is essentially built by hand. No general 
solution to this problem has been proposed be- 
cause each application has its own domain specific 
requirements. 

It is clear, however, that for text generation 
technology to become viable, there must be some 
way to obtain at least portions of the knowledge 
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base automatically. There could be a program 
which automatically derives the knowledge base or 
perhaps the knowledge base could be built as part 
of manual processes that would have to be per- 
formed anyway. Either way, the marginal cost of 
adding text generation would be greatly reduced. 

In this paper, we show that software documen- 
tation is an attractive application for multilingual 
text generation because it is an area in which 
pre-built knowledge bases are becoming available. 
This is due in large part to the advancements in 
the user interface design community which we will 
review first. We then discuss the nature of the 
knowledge base required for the generation of doc- 
umentation and how parts of it might be derived 
automatically. Finally, we illustrate this idea us- 
ing DRAFTER, a Support tool for generating mul- 
tilingual software documentation. 

2 Background 

Researchers in user interface design have started 
to build tools which produce both code and docu- 
mentation. These tools tend to be based on a cen- 
tral model of the interface under development, the 
interface model, a formal representation which can 
be used not only for code generation but also for 



document generation, e.g., (Puerta and Szekely, 
1994| ; [Moriyon et al., 19941 ). Moriyon et al ( |1994| ) 



for example, have used the interface model in the 
generation of on-line help. Their help messages 
indicate the actions a user can perform in a par- 
ticular situation and what would result from these 
actions. They report, however, that task-oriented 
help is beyond the capabilities of their system; 
task-oriented help would indicate why the user 
might want to perform any of the actions that 
are available. 

In general, however, the documentation pro- 
duced by these systems is limited in two main 
ways: it does not correspond to task-oriented doc- 
umentation, which is, however, what end-users re- 
quire and it is usually based on simple template 



generation, which does not allow flexibility with 
regard to the style of the text produced or the 
language that is used. These limitations stem, on 
the one hand, from the fact that interface mod- 
els in general contain system- oriented information 
(e.g., what happens when a button is pushed) but 
not task-oriented information (e.g., why one might 
want to push the button), and, on the other hand, 
from the focus of the research, that is system and 
interface design and not natural language genera- 
tion. 

In the DRAFTER project, we have attempted to 
address these two issues. We address the first 
by providing tools that allow technical authors to 
build richer interface models. These richer mod- 
els integrate task information into the information 
already available in interface models. This task in- 
formation, which is commonly found in task mod- 
els, e.g., GOMS dCard et al., 1983| ), supports the 
production of user-centred documentation. We 
address the second by providing more general text 
generation facilities which support multiple styles 
and multiple languages. 

3 Representing the users' tasks 

Early in the drafter project, we conducted in- 
terviews with technical authors (mostly software 
documentation specialists) in order to understand 
the documentation process as it currently exists, 
to see if an authoring tool would be helpful, and if 
so how it might be used. We found that technical 
authors start the documentation process by learn- 
ing how to use the interface in question, construct- 
ing a user-oriented mental model of the product. 
They frequently have no input other than the soft- 
ware itself. The authors indicated that they would 
welcome tools to help them collect the appropriate 
information and create a formal representation of 
the resulting model. Such a representation would 
support iterative construction of the documenta- 
tion and information reuse. 

Building our drafting tool, therefore, required 
us first to determine how to represent the model 
of a task, and then to build tools for creating and 
manipulating this model. Given that the gen- 
eral structure of instructional texts is hierarchi- 
cal, we chose a representation that expresses a 
hierarchy of goals and sub-goals. The represen- 
tation is thus similar to the traditional struc tures 
found in AI planning, e.g., ( ^acerdoti, 1977 ), and 
also to task model s used in interface design, e.g., 
( Card et al., 1983 ). Because user documentation 
frequently includes information other than the raw 
actions to be performed, our representation allows 
authors to include information not typically found 



in traditional plan representations such as: user- 
oriented motivational goals, helpful side-effects, 
and general comments. 

As an example, consider the representation of 
a sub-set of the procedure for saving a new file in 
a Microsoft Word-like editor shown in Figure |l|. 
The oval boxes in the figure represent actions and 
the rectangles represent plans. Each of the action 
nodes in this structure represent interconnected 
complexes of procedural and descriptive instances. 
For example, the main user goal of saving a docu- 
ment, represented in the figure by the action node 
"Save a Document" , is implemented in the knowl- 
edge base as a complex of instances representing 
the action being performed (in this case saving), 
the agent who performs action (the reader), the 
patient on whom the action is performed (the cur- 
rent document), etc. All of this information is re- 
quired to generate expressions of the action, but 
presenting it would overly complicate the graph. 

The links actually shown in the figure are based 
on the procedural relations in the domain model. 
For example, the plan for saving a document 
(Save-Document-Plan) is linked to its goal (Save 
A Document), to its precondition (Open-Save- 
As), and to its sub-actions of typing a name for the 
current document (Type-Document-Name) , open- 
ing the folder in which it is to be saved (Open- 
Folder), and clicking the Save button (Choose- 
Savc-Button). The precondition (Open-Save- As) 
must be performed before the sub-steps may be at- 
tempted and is in turn linked to further sub-plans 
(Choosing-Plan and Glicking-Plan) . This indi- 
cates that the Save- As dialog box may be opened 
by either choosing the Save option from the file 
menu (Choose-Save-Option) or clicking the Save 
button on the tool bar (Glick-Save-Icon). 

This task model represents the procedures that 
a user might perform when using an application 
and is the basis for generating user-centred docu- 
mentation, such as one of drafter's texts shown 
in Figure ^. It includes the users' high-level goals 
(e.g., "save a document") as well as their low- 
level interface manipulations ("choose the save 
button"). 

4 Input from the Design Process 



In our earlier work, we provided tools that sup- 
ported the construc tion of the task model by hand 
( Paris et al., 1995 ). This went some way to ad- 
dressing the technical authors' desire for a formal 
model and tools to build it. Building the model 
from scratch, however, even with the help of our 
menu based interface, was a tedious and lengthy 
process which could potentially have rendered the 



Precondition 








-lOpen Method 11— 


— ( Choose Save Option ) 


( Open Save As Dialog )<" 




ppen Method 2|— 


— ( Ciick Save Icon ) 



r-F^ tr. r 77—. — 1/ Type Document Name ) 

( Save A Document ) [Save Document Method| fe^^ 

V\M ^Open FoideP ) 
\ x Choose Save Button"") 
\ Plan-Csnceliadon 

( Ouit Save As Diaio^T ) [Cancei Save As Methodj ( Choose Cancei Button ) 



Figure 1: The Saving Procedure Graph 



DRAFTER System impractical. There was a clear 
need for facilities to ease the input task. In line 
with this, we noticed that certain elements of the 
model were also present in the specifications de- 
veloped in user interface design environments. In- 
deed, we found that a number of the actions and 
objects in the model could be automatically ac- 
quired from a design tool, thus providing basic 
building blocks from which the full model could 
be constructed. 

To illustrate this idea, we have built our exam- 
ple document editor application in VisualWorks, 
a widely available interface design environment 
(Vis, 1994). This tool allows one to define the 
windows, dialog boxes, and other widgets relevant 
for the application under development, and pro- 
duces a prototype of the interface thus specified. 
Its output also includes declarative specifications 
of all the widgets. These specifications are thus 
available to be exploited by other systems. In par- 
ticular, we found that these specifications could be 
readily transformed into a form appropriate for 
the knowledge base required by a text generation 
system such as drafter. In our example then, we 
build a VisualWorks mock-up of our word process- 
ing application, and drafter derives task model 
instances for all the windows and widgets in the 
application (e.g., the Save- As dialog box and all its 
widgets) directly from the SmallTalk source code. 
DRAFTER is also able to infer the basic interface 
actions that can be performed on the various in- 
terface widgets and creates task model instances 
for them as well. For example, the system auto- 
matically defines a clicking action instance for any 
"button" on the interface. Similarly, it creates 
opening and closing actions for all "windows" . 

Although this set of instances does not repre- 
sent all the information that could, in principle, 
be derived from the SmallTalk specifications of 
the editor application, it nevertheless simplifies 
greatly the technical author's task of knowledge 



specification by providing the building blocks from 
which higher-level procedures can be defined. In 
the case of our admittedly simple example, seven 
of the nine actions in the procedural structure are 
automatically specified. The author is required 
to specify only the main user goal action and the 
three plan nodes. This is, therefore, a step to- 
wards automatically building the knowledge base 
required for the generation system. It is also a step 
towards integrating the design and documentation 
processes, which is now widely recognised as be- 
ing desirable. In our current work, we are investi- 
gating how more of the design knowledge can be 
made accessible and understandable to the tech- 
nical authors, and what other tools would further 
facilitate the authors' task. We are also looking 
at a tighter integration of the design and docu- 
mentation processes, one in which the individuals 
involved work together during design. 

5 DRAFTER 

We now describe drafter, a technical authoring 
tool which supports the construction of the task 
model discussed above and the drafting of multi- 
lingual instructions from that model. We will fo- 
cus on how it supports the author in augmenting 
the information automatically acquired from the 
interface design tool, drafter's general archi- 
tecture, shown in Figure H, is based on two main 
processing modules: 

• The Author Interface (shown on the far 
left of the diagram) allows authors to 
build a task model and to control the 
drafting process. 

• The Drafting Tool (shown on the far 
right of the diagram) comprises two ma- 
jor components: the Text Planner and 
the Tactical Generator. The Text Plan- 
ner determines the content and structure 
of the text as well as the detailed struc- 
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Figure 2: Dataflow in drafter 



ture of the sentences therein. The Tacti- 
cal Generator performs the surface real- 
isation of the sentences. 

The knowledge base (in the middle of the figure) 
underlies the task model built by the technical au- 
thor. The Drafting Tool takes this representation 
as input and produces English and French drafts 
of the appropriate tutorial instructions. In this 
section we detail each of these components in the 
context of an example. 

5.1 The Knowledge Base 

The knowledge base supports the construction of 
the task model discussed above. It is an hierarchi- 



cal st ructure implemented in LOOM (MacGregor 
1988 ). The root is the Penman Merged Upper 
Model ( Bateman, 1995 ), an ontology of distinc- 



tions relevant in expressing actions, objects, and 
qualities in natural language. The knowledge base 
contains further layers corresponding to: (1) the 
concepts and relations general to all instructions; 

(2) those general only to software interfaces; and 

(3) those specific to the chosen software applica- 
tion domains (in our case text processing tools). 

Using the drafter interface, technical authors 
specify hierarchical task models, such as the one 
shown in Figure |l], by building nodes and con- 
necting them with the appropriate procedural re- 
lations. The low-level building blocks of the task 
model are derived automatically, and drafter 
allows the technical author to connect them and 
add higher-level task information as appropriate, 
using an interface based on controlled language 
and the use of menus to guide the author. 



5.2 The Interface 

drafter's interface is implemented in glim and 
includes the following modules: 

• The Knowledge Editor allows the author 
to construct and maintain the procedural 
representation; 

• The Knowledge Grapher allows the au- 
thor to visualise the hierarchical struc- 
ture of the procedural representation; 

• The Draft Text Viewer allows the author 
to view and edit the automatically gen- 
erated English and French drafts. 

These functions can be invoked from menus or 
from mouse-sensitive objects in a style common 
to systems such as Motif. 

5.2.1 The Knowledge Editor 

This tool makes the structure of the knowledge 
base on which the task model is built more ac- 
cessible to the author. It allows the author to 
perform two basic tasks: (1) specifying the ac- 
tion nodes appearing in the structure and not yet 
derived from the interface designed tool; and (2) 
linking existing nodes together with the appropri- 
ate plan instances and relations. The first of these 
tasks is performed using a controlled natural lan- 
guage interface while the second is done with a 
dialog box mechanism. 

Specifying the nodes appearing in the task 
model involves specifying a full complex of lin- 
guistic entities and role-fillers (e.g., actors, actees, 
destinations). Because this structure may include 
many instances interconnected in potentially un- 
intuitive ways, we have provided a Controlled Nat- 
ural Language (CNL) interface for the author. 



The interface is shown in Figure ^. This interface 
allows the author to work in terms of sentences 
rather than in terms of interconnected graphs. 
The figure, for example, shows the author in the 
process of specifying the node Save A Document. 
The top line of text (reader save [information]) 
shows the current state of the CNL specification. 
Words in brackets must be further specified. This 
is done by clicking on the word and selecting the 
appropriate pattern from a list of possible expan- 
sions. In the figure, the author has clicked on 
[information] and is presented with a list of the 
types of information from which [document] can 
be selected. This process is driven by a controlled 
natural language grammar which specifies possible 
expansions at each point of the derivation. The 
bottom line of text presents a fully expanded de- 
fault at each point in the derivation. In the figure, 
this CNL text is "reader save current document" 
which could be expressed in English in a number 
of ways including "Save the current document" 
and "To save the document" . 

Once the action nodes of the graph have been 
created, or perhaps while they are being created, 
the author has the ability to link them together us- 
ing a set of predefined procedural relations: goal, 
precondition, sub- action, side-effect, warning, and 
cancellation. This is done with a graphical outlin- 
ing mechanism. This mechanism allows authors to 
drag actions from the ACTIONS pane and drop 
them on the various procedural relation slots in 
the workspace pane, or, alternatively, to create 
new actions to fill the slots. The result is a proce- 
dural hierarchy such as the one shown in Figure |^. 

This interface allows the author to specify the 
procedure in several ways. They may start from 
the main goal and work down the structure, or 
they may start by specifying all the low-level ac- 
tions and object and work up the structure. 

5.2.2 The Knowledge Grapher 

The Knowledge Grapher prevents the author 
from losing orientation by maintaining the cur- 
rent state of the procedural structure in graphical 
form. This form is like that shown in Figure]^. Be- 
cause the nodes are mouse-sensitive, it allows the 
author to initiate construction and maintenance 
functions by clicking on the appropriate nodes in 
the graph. Authors can also invoke the drafting 
tool from the graph. 

5.2.3 The Draft Text Vievirer 

The author may draft multilingual instructions 
on any portion of the procedural structure at any 
point in the specification process. This task is 
performed by the Drafting Tool which is briefly 



described in the next section. This tool pro- 
duces a draft of the instructions in English and 
French. These are presented to the author by the 
Draft Text Viewer. The presented text is mouse- 
sensitive, allowing the author to access the knowl- 
edge base entry for selected part of the text. In 
this way, the author can modify the underlying 
knowledge base while working from the text. In 
some cases the writer will decide to modify the 
generated text rather than the underlying knowl- 
edge. For this purpose, a text editor is currently 
provided. 

5.3 The Drafting Tool 

When the author initiates the Drafting Tool (see 
Figure ||), drafter calls the Text Planner with 
the discourse goal: make the user competent to 
perform the action specified by the author. The 
Text Planner selects the content appropriate for 
the instructions and builds a deep representation 
of the text to be generated. This portion of the 
text planning task is done by the text planner de- 
veloped by Moore and Paris (1993). The Text 
Planner then specifies the detailed elements of the 
sentence structure. This portion of the task is 



done by a descendent of imagene (Vander Lin- 
den and Martin, 1995). 

Once complete, the text plans are passed to 
the Tactical Generator which generates the actual 
text in English and French. This task is performed 
by the English and French resources of the Komet- 
Penman Multi-Lingual development environment 
(KPML) dBatcman, 1995D , The drafts generated 
for the example procedure are shown in Figure ^. 

In these texts, we see that the main user goal, 
that of saving a document, is given as a title to the 
series of steps. Then, the steps to be performed 
to achieve this goal are given. More detail on the 
drafting process can be found elsewhere. 

6 Summary 

In this paper, we have shown that the knowl- 
edge base required to produce user-oriented docu- 
mentation automatically can be partially obtained 
from user interface tools and then augmented ap- 
propriately by technical authors. We presented a 
multilingual drafting tool which exploits output 
from an interface design tool and provides flexible 
support to technical authors for augmenting the 
interface model thus obtained in order to build the 
task model required to generate documentation. 
We argued that software documentation is thus 
an attractive and realistic application for natural 
language generation. In our current work, we are 
extending the percentage of the model that can be 
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Figure 3: The Controlled Natural Language Interface 



To Save a Document 

1. Choose Save from the file menu. 
-OR- 

Click on the Save icon. 

Word displays the Save As dialog box. 

2. Type the document name in the Save Cur- 
rent Document As field. 

3. Open the folder of the document. 

4. Choose the Save button. 

You can quit the Save As dialog box by choos- 
ing the Cancel button. 



Enregistrement d'un document 

1. Choisir Enregistrer dans le menu Fichier. 
OU BIEN 

Cliquer sur I'icone Enregistrer. 

Word affichera la zone de dialogue Enregistrer Sous. 

2. Introduire le titre du document dans la zone de 
texte Enregistrer le Document. 

3. Ouvrir le fichier du document. 

4. Choisir le bouton Enregistrer. 

Vous pouvez quitter la zone de dialogue Enregistrer 
Sous en choisissant le bouton Annuler. 



Figure 4: Generated English and French Drafts 



built automatically, so as to increase the useful- 
ness of the system and its potential marketability. 
We are also planning to evaluate the system with 
technical authors. 
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